home *** CD-ROM | disk | FTP | other *** search
/ United Public Domain Gold 2 / United Public Domain Gold 2.iso / utilities / pu325.dms / pu325.adf / EZAsm / EZAsm.doc < prev    next >
Text File  |  1992-08-04  |  27KB  |  1,247 lines
  1.  
  2.  
  3.     EZAsm   Version 1.6         September '91   by Joe Siebenmann
  4.  
  5.  
  6.     DISCLAIMER:
  7.  
  8.     The following only applies to EZAsm, ez.lib, funcnm2, funcdat2,
  9.     and related .doc files.  ( A68k & Blink have their own
  10.     distribution policies )
  11.  
  12.     You have the right to freely use, copy and distribute this program
  13.     as long as the following conditions are met:
  14.  
  15.     1.    The documentation is included with the program, and neither
  16.         is modified in any way.
  17.  
  18.     2.    The program is not included in any package for profit
  19.         unless written consent from the author is obtained.
  20.  
  21.     NOTE: The author does not accept any responsibility for any damage
  22.            that might result from the use of this program.
  23.  
  24.  
  25.  
  26.  
  27.         ---  New for Version 1.6  ---
  28.  
  29. o    All 2.0 functions are now supported.
  30.  
  31. o    Output is now completely compatible with, and will
  32.     assemble without changes under:  A68k, Manx, and Lattice.
  33.     ( for Lattice, change the extension from ".asm" to ".a" )
  34.  
  35. o    Bug fixes:
  36.  
  37.     -  Problem with conditional assembly statements, and
  38.        macros ( IFD/IFND ENDC, MACRO ENDM ) placed before "END".
  39.  
  40.     -  Problem with generating .asm files greater than 32,767
  41.        bytes.  Thanks to Jan Geissler for reporting the bug.
  42.  
  43.     -  Problem calling EZAsm with no arguments.
  44.        
  45. o    Mk ( Make1 ) now has support for an optional include path for
  46.     A68k, and support for a .mak file.
  47.  
  48. o    Additional improvements and optimizations.
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.     EZAsm was written to make programming in 68000 assembly
  56.     language much easier!  EZAsm combines parts of "C" with
  57.     68000 assembly, giving it the "feel" of a higher level language.
  58.     The resulting code is optimized as much as possible.
  59.  
  60.     A68k ( by Charlie Gibbs ) and Blink ( from The Software Distillery )
  61.     are included, and the offsets for all the 2.0 functions are
  62.     internal, so you'll have everything you need to start
  63.     producing executables ( except the include files ( if you need them )).
  64.  
  65.  
  66. Here are some of its advantages:
  67.  
  68.  
  69. o    Your code is converted into the fastest possible
  70.     assembly statement(s), so you automatically write
  71.     "good" code.
  72.  
  73. o    More structured.  Compare and bit test statements can have
  74.     braces and "else" like "C".  Being able to use braces lets
  75.     you use assembly in a whole new way!
  76.  
  77. o    "C" like Amiga function calls!  Every 2.0 function in every
  78.     library is supported.
  79.  
  80. o    Your code is much more readable, and easier to debug.
  81.     You can code nearly twice as fast, with fewer syntax errors.    
  82.  
  83. o    No more having to constantly look up which condition code to    
  84.     use for compares, bit tests, or maximum numbers for
  85.     "moveq" or "addq" etc.
  86.  
  87. o    You can freely mix "EZAsm statements" and normal
  88.     assembly statements.
  89.  
  90.  
  91.  
  92.     You need to know a little about assembly language and
  93.     "C" operators before you dive right in.  If you're new to
  94.     68000 assembly language, I suggest looking at one of the
  95.     many available books on the subject.  The included example
  96.     source programs can give you a good idea about:
  97.  
  98.  
  99. o    General statement syntax.
  100.  
  101. o    Use of "l", "w", "b" size arguments.
  102.  
  103. o    Using assembly statements in your code.
  104.  
  105.  
  106. ****************************************    
  107.  
  108. Using EZAsm:
  109.  
  110.     1.  Create a directory, and copy these files into it:
  111.  
  112.         EZAsm, A68k, Blink, Mk, ez.lib, funcnm2, funcdat2
  113.  
  114.     2.  CD into your new directory, and you're ready to go!
  115.  
  116.     ( Another good method is to create an ALIAS to load these
  117.     files into VD0: and work from there )
  118.  
  119.  
  120. Mk
  121.  
  122.     Mk is a "make" like program, written in EZAsm, that will
  123.     Execute() the necessary programs for you, creating an
  124.     executable file with a minimum of effort.  It also
  125.     supports an optional include path for A68k, and support
  126.     for a ".mak" file.  The source code is included.
  127.  
  128.     With include path:
  129.  
  130.         Mk -iPathToIncludes file
  131.  
  132.     Without include path ( also for .mak ):
  133.  
  134.         Mk file
  135.  
  136.     ( where "file" is your source file with path if needed
  137.     ( No extension ))
  138.  
  139.  
  140.         Execute()'s these commands:
  141.  
  142.         ezasm file.s
  143.         a68k [-iPathToIncludes] file.asm
  144.         blink FROM file.o LIBRARY ez.lib TO file
  145.  
  146. .mak
  147.  
  148.     For times when you need to supply more options for A68k
  149.     or Blink, Mk now supports a .mak file.  Just create a file
  150.     with the same name as your source file, but with a ".mak"
  151.     extension.  The file should contain the EZAsm, A68k, and
  152.     Blink commands with any options/switches you need, as if
  153.     you were entering them from the CLI.  Any comments should
  154.     begin with a non-alpha character.  If Mk finds the .mak 
  155.     file, it will Execute() those commands, otherwise it will
  156.     Execute() the standard commands.
  157.  
  158.  
  159.  
  160.  
  161. ************************************
  162. *         Operand  Table           *
  163. ************************************
  164.  
  165.                  Operand Type
  166.  
  167. Mode       [A] [B] [C] [D] [E] [F]
  168.  
  169. Dn          *   *   *   -   *   -
  170. An          *   -   *   -   -   -
  171. (An)        *   *   *   *   *   *
  172. (An)+       *   *   *   *   *   *
  173. -(An)       *   *   *   *   *   *
  174. d(An)       *   *   *   *   *   *
  175. d(An,Xn)    *   *   *   *   *   *
  176. 16 bit addr *   *   *   *   *   *
  177. 32 bit addr *   *   *   *   *   *
  178. d(PC)       *   -   -   -   *   *
  179. d(PC,Xn)    *   -   -   -   *   *
  180. immediate   *   -   -   -   *   -
  181.  
  182.  
  183. declared variables:
  184.  
  185. "foo"  becomes  "foo(a5)"  ( d(An) )
  186.  
  187. **************************************
  188.  
  189.  
  190. #<1>    1 - 8
  191. #<2>    0 - 7
  192. #<3>    0 - 31
  193. #<q>    -128 - 127
  194. #<any>    any byte, word, or long size number
  195.  
  196.  
  197. Dn    d0 - d7
  198. An    a0 - a7
  199.  
  200.  
  201. {B}    byte data size not allowed for An operands
  202.  
  203.  
  204. ********************************************
  205. *      legal      *  converted   *  legal  *
  206. *     operands    *     to       *  sizes  *
  207. ********************************************
  208.  
  209. Addition  Subtraction
  210.  
  211. ++
  212. --
  213.  
  214.     [C] <op>        addq/subq       L,W,{B}
  215.  
  216. +=
  217. -=
  218.     
  219.      Dn <op> [A]    add/sub         L,W,B        
  220.  
  221.     [D] <op> Dn     add/sub         L,W,B
  222.  
  223.      An <op> [A]    adda/suba       L,W
  224.     
  225.     [B] <op> #<any> addi/subi       L,W,B        
  226.     
  227.     [C] <op> #<1>   addq/subq       L,W,{B}    
  228.  
  229.  
  230. Examples:
  231.  
  232.     Total ++    
  233.     d1 += 10
  234.  
  235. Optional Args:
  236.  
  237.     l, w, b 
  238.  
  239. ********************************************
  240.  
  241. Multiplication   Division
  242.  
  243.  
  244. *=
  245.  
  246.     Dn *= [E]       mulu            W
  247.  
  248.     Dn *= ##   *                    W
  249.  
  250.  
  251. /=
  252.  
  253.     Dn /= [E]       divu            W
  254.     
  255.  
  256. Examples:
  257.  
  258.     d0 *= d1
  259.     d2 /= 2
  260.  
  261. Optional Args:
  262.  
  263.     w,
  264.     s ( signed  divs/muls )
  265.  
  266.  
  267. *    This optimization results in code that's larger then "mulu"
  268.     or "muls", but will execute much faster.  Not all numbers
  269.     can be optimized.  If the number doesn't work, "mulu"
  270.     or "muls" will be used.
  271.  
  272.     ( where ## is a word or byte length number )
  273.  
  274.  
  275. *********************************************
  276.  
  277. And   Or   Exclusive Or
  278.  
  279.  
  280. &=
  281. |=
  282.  
  283.     [B] <op> #<any>     andi/ori        L,W,B    
  284.     
  285.      Dn <op> [E]        and/or          L,W,B
  286.     
  287.     [D] <op> Dn         and/or          L,W,B
  288.  
  289.  
  290. x=
  291.  
  292.     [B] x= Dn           eor             L,W,B    
  293.     
  294.     [B] x= #<any>       eori            L,W,B
  295.  
  296.  
  297. Examples:
  298.  
  299.     Mask &= %11010000
  300.     Flags |= $f0
  301.  
  302. Optional Args:
  303.  
  304.     l, w, b 
  305.  
  306. *********************************************
  307.  
  308. Shift  Left/Right
  309.  
  310.  
  311. <<
  312. >>
  313.  
  314.      Dn <op> Dn     lsl/lsr         L,W,B
  315.     
  316.      Dn <op> 1-31 * lsl/lsr         L
  317.  
  318.      Dn <op> 1-8    lsl/lsr         L,W,B
  319.     
  320.     [D] <op> 1      lsl/lsr         W
  321.  
  322.  
  323. Examples:
  324.  
  325.     d2 << d0
  326.     d1 >> 4
  327.  
  328. Optional Args:
  329.  
  330.     l, w, b,
  331.     a ( arithmetic shift  asl/asr )
  332.  
  333.  
  334. *    Normally you're limited to shifting 1-8, or using a
  335.     data register to hold higher.  This optimized version
  336.     is faster, and saves using a data register!
  337.     ( logical shift only )
  338.  
  339.     
  340. *********************************************
  341.  
  342. Assign
  343.  
  344.  
  345. =    
  346.  
  347.     [B] = [A]    move            L,W,{B}
  348.     
  349.      An = [A]    movea           L,W
  350.     
  351.      Dn = #<q>   moveq           L
  352.  
  353.  
  354. Examples:
  355.  
  356.     temp = Total
  357.     (a1)+ = 0 w
  358.  
  359. Optional Args:
  360.  
  361.     l, w, b 
  362.  
  363. ********************************************
  364.  
  365. Compare
  366.  
  367.  
  368. >=
  369. <=
  370. !=
  371. >
  372. <
  373. =
  374.  
  375.      Dn <op> [A]      cmp          L,W,{B}
  376.     
  377.      An <op> [A]      cmpa         L,W
  378.     
  379.     [B] <op> #<any>   cmpi         L,W,B
  380.     
  381.   (An)+ <op> (An)+    cmpm         L,W,B
  382.  
  383.  
  384.  
  385. Syntax types:
  386.  
  387.  
  388.     [opr] <op> [opr] label
  389.  
  390.  
  391.  
  392.     [opr] <op> [opr] {
  393.         .
  394.         .
  395.     }
  396.  
  397.  
  398.  
  399.     [opr] <op> [opr] {
  400.         .
  401.         .
  402.     
  403.     } else {
  404.         .
  405.         .
  406.     }
  407.  
  408.  
  409. Examples:
  410.  
  411.     Total >= 100 Over
  412.  
  413.     Buf != 0 {
  414.         FreeMem( Buf 100 )
  415.     }
  416.  
  417.  
  418. Optional Args: ( placed AFTER label or brace )
  419.  
  420.     l, w, b,
  421.     s ( signed )
  422.  
  423.  
  424. *********************************************
  425.  
  426. Bit test
  427.  
  428.  
  429.  
  430.     Dn:0-31  =  0-1    btst.l     L
  431.     
  432.     Dn:Dn    =  0-1               L
  433.     
  434.     
  435.     [F]:0-7  =  0-1    btst.b     B    
  436.     
  437.     [F]:Dn   =  0-1               B
  438.  
  439.  
  440.  
  441. Syntax types:
  442.  
  443.  
  444.     [opr] <op> [opr] label
  445.  
  446.  
  447.  
  448.     [opr] <op> [opr] {
  449.         .
  450.         .
  451.     }
  452.  
  453.  
  454.  
  455.     [opr] <op> [opr] {
  456.         .
  457.         .
  458.     
  459.     } else {
  460.         .
  461.         .
  462.     }
  463.  
  464.  
  465. Examples:
  466.  
  467.     d1:0 = 0 EvenRtn
  468.  
  469.     ($bfe001):6 = 0 LMBDown
  470.  
  471.     d2:d0 = 1 {
  472.         rts
  473.     }
  474.  
  475.  
  476. Optional Args:
  477.  
  478.     ( ignored )
  479.     
  480. Rules:
  481.  
  482. o    No spaces inside first operand.
  483.  
  484. o    Only "=" is allowed.
  485.  
  486. o    Right operand can only be 0 or 1.
  487.  
  488.  
  489. *********************************************
  490.  
  491. Additional Arguments:
  492.  
  493.  
  494. b   forces operation to be byte
  495.  
  496. w     "       "        "   word
  497.  
  498. l     "       "        "   long
  499.  
  500. a    arithmetic shift       ( <<, >> )
  501.  
  502. s    signed                 ( *=, /=, compares )
  503.  
  504.  
  505. ( these are RESERVED and can't be used as variables, or labels
  506. ( unless you use upper case ) ) 
  507.  
  508. *********************************************
  509.  
  510. Functions:
  511.  
  512.  
  513. Syntax examples:
  514.  
  515.     CloseWindow( Window )
  516.  
  517.     Buf = AllocMem( 512 #CLEAR_PUBLIC )
  518.  
  519.     Permit( )
  520.  
  521.  
  522.  
  523. Example:
  524.  
  525. --------------------------------
  526.  
  527.  
  528. CLEAR_PUBLIC  equ  $10001
  529. OLDFILE       equ  1005
  530.  
  531.  
  532.  
  533. LONG    _DosBase FHandle num Rbuf 
  534.  
  535.  
  536.  
  537.     _DosBase = OpenLibrary( "dos.library" 0 ) 
  538.     beq  Exit
  539.  
  540.     Rbuf = AllocMem( 100 #CLEAR_PUBLIC )
  541.     beq  Exit
  542.  
  543.     FHandle = Open( "df0:myfile" #OLDFILE )                 
  544.     beq  Exit
  545.  
  546.     d3 = 100    ; preload D3   *1
  547.     num = Read( d0 Rbuf * )
  548.  
  549.         .
  550.         .
  551.         .
  552.  
  553.  
  554. *1   normally you wouldn't need to do this, it's only an example..
  555.  
  556. ---------------------------------
  557.  
  558.  
  559. o    All 2.0 functions are now supported.
  560.     Don't worry, the older 1.3 functions are still there.
  561.     Some 2.0 functions are "for internal use only",
  562.     some "OBSOLETE", some functions may have been deleted,
  563.     or added.  Check "funcnm2" for supported function names.
  564.     ( AllocWBObject( ), FreeWBObject( ), GetWBObject( ),
  565.     PutWBObject( ) in IconBase, are listed as "OBSOLETE"
  566.     but are still included )
  567.  
  568. o    You must first do an OpenLibrary( ) to access functions in
  569.     a library.  Functions in ConsoleDevice are accessed 
  570.     differently, see the ConsoleDevice section in the RKM p 662.
  571.     ( load the io_Device field into "_ConBase" )
  572.     Functions in ExecBase ( SysBase ) are always accessible and don't
  573.     need to be opened.
  574.  
  575.     The library bases MUST be named:
  576.  
  577.  
  578.     _AslBase
  579.     _BattClockBase
  580.     _BattMemBase
  581.     _ConBase
  582.     _CxBase
  583.     _DiskBase
  584.     _DiskfontBase
  585.     _DosBase
  586.     _ExpansionBase
  587.     _GadToolsBase
  588.     _GfxBase
  589.     _IconBase
  590.     _IFFParseBase
  591.     _InputBase
  592.     _IntuitionBase
  593.     _KeymapBase
  594.     _LayersBase
  595.     _MathBase
  596.     _MathIeeeDoubBasBase
  597.     _MathIeeeDoubTransBase
  598.     _MathIeeeSingBasBase
  599.     _MathIeeeSingTransBase
  600.     _MathTransBase
  601.     _MiscBase
  602.     _PotgoBase
  603.     _RexxSysBase
  604.     _TimerBase
  605.     _TranslatorBase
  606.     _UtilityBase
  607.     _WorkbenchBase
  608.  
  609.  
  610.  
  611. o    Unfortunately the leading underscores are necessary so you can
  612.     use includes without your assembler complaining.  Some library
  613.     bases are already defined in some .i's resulting in
  614.     "multiply defined symbol" errors.
  615.  
  616. o    You might notice that ExecBase is missing.  It isn't needed.
  617.     ( it's loaded with "movea.l $4,a6" )
  618.  
  619.  
  620.                    Permit( )
  621.               OpenLibrary( "dos.library" 0 )
  622.                         ^ ^               ^
  623.                no space | | space         | space
  624.  
  625. o    The function name must be followed immediately with "("
  626.     ( no spaces between ) and then followed by a space or tab.
  627.     If the function has no arguments, it still needs a space in
  628.     the middle.  Arguments must be separated with a space or tab.
  629.  
  630.  
  631.               ReturnVar = AllocMem( FSize $10001 )
  632.  
  633. o    All variables used in function calls, return variables or
  634.     function arguments, should be LONG.
  635.  
  636.  
  637.               a2 = ViewAddress( )
  638.               d1 = Read( "myfile" Buf BufLen )
  639.  
  640. o    Address or data registers can also be used for returns
  641.     if they're more convenient.
  642.     ( returns to D0 are now ignored, as it produces a useless
  643.     "move.l d0,d0" instruction )
  644.  
  645. o    Several people were concerned when their OpenWindow( ) and
  646.     OpenScreen( ) calls crashed.  The included example source
  647.     "scrwin.s" opens a screen and a window, and is a good
  648.     "base" for starting similar programs.  Problems occur  
  649.     when the NewWindow fields "IDCMPFlags" and "Flags" are
  650.     incorrectly switched, or fields arn't aligned.
  651.     ( not word aligned at the start, or fields the wrong size )
  652.     ( also include any filler "kludge" bytes, as they're also
  653.     important for field "alignment" )
  654.  
  655.  
  656.  
  657. Arguments:
  658.  
  659. o    If your argument is already in a DIFFERENT data or address register,
  660.     you can pass it as an argument directly.  Often a previous function
  661.     will put results in D0, so just pass d0.  If the proper
  662.     register is already loaded, just pass "*".
  663.  
  664.     ( if you pass it the same register it uses, it'll be skipped.
  665.     func defined as:  D0 = Lock( D1 D2 )  "Flock = Lock( d1 -2 )"
  666.     arg "d1" will be skipped )
  667.  
  668.  
  669. o    EZAsm supports argument strings surrounded by double quotes.
  670.     The following "C" character constants are supported:
  671.  
  672.         \b    backspace
  673.         \f    form feed
  674.         \n    newline
  675.         \r    carriage return
  676.         \t    horizontal tab
  677.         \v    vertical tab
  678.  
  679.  
  680.     examples:  
  681.  
  682.     "Hello, World!\n"
  683.     
  684.     "\t\tHeading\n"
  685.  
  686.  
  687.     ( strings are automatically null terminated )
  688.  
  689.  
  690.  
  691.  
  692.  
  693. NewWin    ds.w    0        ;align
  694.     dc.w    0,0,640,200
  695.     dc.b    -1,-1
  696.     .
  697.     .
  698.  
  699.  
  700. o    To load a pointer to a NewWindow or other "structure" you've
  701.     defined use: #NewWin ( etc. ) it'll load its address into
  702.     a data or address register.
  703.  
  704. o    if you need a pointer to one of your declared variables
  705.     ( where the argument goes to an address register ) use:
  706.  
  707.         &foo   ( address of "foo" )
  708.  
  709.     ( output as "lea  foo(a5),An" )
  710.     ( "&" is ONLY recognized inside function arguments )
  711.  
  712. o    Sometimes you have to "play around" with using "#", "&", variables,
  713.     constants etc.  You might be giving it the contents of a variable,
  714.     when it needs its address ( etc. )
  715.   
  716.  
  717. All functions within these 2.0 libraries are supported:
  718.  
  719.  
  720.     AslBase
  721.     BattClockBase
  722.     BattMemBase
  723.     ConBase
  724.     CxBase
  725.     DiskBase
  726.     DiskfontBase
  727.     DosBase
  728.     ExecBase ( SysBase )
  729.     ExpansionBase
  730.     GadToolsBase
  731.     GfxBase
  732.     IconBase
  733.     IFFParseBase
  734.     InputBase
  735.     IntuitionBase
  736.     KeymapBase
  737.     LayersBase
  738.     MathBase
  739.     MathIeeeDoubBasBase
  740.     MathIeeeDoubTransBase
  741.     MathIeeeSingBasBase
  742.     MathIeeeSingTransBase
  743.     MathTransBase
  744.     MiscBase
  745.     PotgoBase
  746.     RexxSysBase
  747.     TimerBase
  748.     TranslatorBase
  749.     UtilityBase
  750.     WorkbenchBase
  751.  
  752.  
  753.  
  754.  
  755. o    It keeps track of the current library base.  As long as no user
  756.     labels, or close braces ("}") are hit, it will skip reloading
  757.     the base register for functions which use the same
  758.     library base.
  759.  
  760. o    The file "funcnm2" contains a list of every function that is
  761.     supported.
  762.  
  763.  
  764. *********************************************
  765.  
  766. Optimizations:
  767.  
  768.     In addition to the many "normal" optimizations performed
  769.     on statements, the following are also performed:
  770.  
  771.  
  772.   STATEMENT          BECOMES        NOTE
  773.  
  774.  
  775.    An = 0          sub.l An,An
  776.  
  777.    [B] = 0         clr [B]          1
  778.  
  779.  
  780.  ( compares )
  781.  
  782.    [B] < 0
  783.    [B] >= 0                         5
  784.  
  785.    [B] = 0
  786.    [B] != 0        tst [B]
  787.                    bxx label
  788.  
  789.    ----------------------------------
  790.  
  791.    [B] += #<q>
  792.    [B] -= #<q>
  793.  
  794.    [B] &= #<q>   
  795.    [B] |= #<q>
  796.    [B] x= #<q>
  797.  
  798.    [B] = #<q>      moveq   #<q>,d7  2
  799.                    [opr].l d7,[B]
  800.  
  801.  
  802.    ( compares )
  803.  
  804.    Dn <op> #<q>    moveq   #<q>,d7  2
  805.                    cmp.l   d7,dn
  806.                    bxx     label
  807.  
  808.    An <op> #<q>    moveq   #<q>,d7  2
  809.                    cmpa.l  d7,an
  810.                    bxx     label
  811.  
  812.    ----------------------------------
  813.  
  814.    An += #1        lea  n(An),An
  815.    An -= #1        lea  -n(An),An   3, 2
  816.  
  817.    An = #<any>     lea  n,An        4, 2
  818.  
  819.    
  820.  
  821.  
  822. #1 = maximum:  -= 32768   += 32767
  823.  
  824.  
  825. Notes:
  826.  
  827. 1    For byte and word sizes the code size is smaller, for long,
  828.     its smaller and faster. ( then "move #0,[B]" )            
  829.  
  830. 2    Only apply to long sized operations.
  831.  
  832. 3    ( 1-8 handled by "addq", "subq" )
  833.  
  834. 4    ( 0 handled by "sub.l An,An" )
  835.  
  836. 5    Taken as signed.
  837.  
  838.  
  839. *********************************************
  840.  
  841. General Info:
  842.  
  843.  
  844. o    Statements can be indented as you like.  Operands, operator,
  845.     and arguments must be separated by at least one space or tab. 
  846.  
  847. o    Braces can be nested up to 30 deep.
  848.     
  849. o    Only one statement per line.
  850.  
  851. o    If you declare variables or use function call's, the first statement
  852.     in your code must be an "EZAsm statement" so it knows when
  853.     to insert the XREF's and/or get stack frame for the
  854.     variables.  Comments, assembly directives, or assembly statements
  855.     placed between your variables and the start of your code will be
  856.     OUT OF PLACE in the output file.
  857.  
  858. o    Comments must begin with "*" or ";" and begin at column 1, or after
  859.     statements ( separated from last argument or operand ) using ";".
  860.     ( both types are transferred to output file ( some may not ))
  861.  
  862. o    Operands supported:  @141 (octal),  $61 (hex),  %1100001 (binary),
  863.     'a' (ASCII),  97  (decimal).  ASCII strings in operands can
  864.     contain a maximum of 4 characters.
  865.     ( no quotes within quotes permitted )    
  866.  
  867. o    To make labels and symbols as compatible as possible, they arn't
  868.     checked for illegal characters.  Typically the 1st character
  869.     must be a letter, underscore "_", or a period "." .
  870.     The rest of the characters can be any of these plus 0-9.
  871.  
  872. o    Labels and symbols are limited to a length of 127.
  873.     ( Check your assembler to find what length they're
  874.     significant to ( usually around 30))
  875.  
  876. o    Labels that don't begin at column 1 should be followed immediately
  877.     with ":".
  878.  
  879. o    Temporary labels of the form n$, where n consists of decimal
  880.     digit(s), are supported.  These labels are only in effect till
  881.     the next non-temporary label is encountered.  ( be careful
  882.     of "hidden" labels generated by braces )
  883.  
  884. o    No need to put in the usual "moveq #0,d0", "rts" at the end of your
  885.     code, its part of the closing block of code it inserts.
  886.  
  887. o    D7 is used as a scratch register for some optimizations, so be
  888.     careful if you use it.
  889.  
  890. o    Labels that it generates for braces are in the range
  891.     ".laaa" to ".lzzz" so try to avoid using them.
  892.     ( upper case is OK )
  893.  
  894. o    Constants generated from argument strings are in the range:
  895.     .c0 to .c0+n .  Matching strings are not duplicated.
  896.   
  897. o    "SP", "PC", "CCR", "SR" & "USP" ( upper or lower case )
  898.     are supported, but you must ensure the size is legal etc.
  899.  
  900. o    For best viewing of output file set your tabs to 8 spaces.
  901.     ( printing should be fine )
  902.  
  903.  
  904. IMPORTANT! :
  905.  
  906. Use of register A5 is RESERVED!
  907.  
  908. ( it contains the base address for variable storage )
  909.  
  910.  
  911. *********************************************
  912.  
  913. Variable Declaration:
  914.  
  915.  
  916. LONG    foo Save[10] bar
  917. WORD    DMASave
  918. BYTE    Sw
  919.  
  920.  
  921. o    "xxx[n]" reserves n consecutive blocks of given size,
  922.     with "xxx" pointing to left-most byte.
  923.     ( this is for advanced users who need a convenient
  924.     way to allocate SMALL chunks of memory for saving
  925.     registers etc. )
  926.  
  927. o    You're limited to 14 variables per line.
  928.  
  929. o    No other statement types may occur between these lines.
  930.  
  931. o    Variables must be separated by at least one space, or tab.
  932.  
  933. o    To keep things word aligned, if an odd number of bytes are    
  934.     declared in BYTE, an extra byte will be added.
  935.     ( this will offset the next "equ" by one )
  936.  
  937. o    Must occur JUST BEFORE your program code.
  938.  
  939. o    Must begin at 1st column, with LONG, WORD, or BYTE in upper case.
  940.  
  941. o    EZAsm uses "link" to allocate space for variables on the stack.
  942.     The maximum size of this space is 32K.  Since this stack space
  943.     contains "garbage", code is added to clear it out before use.
  944.     ( A0 and D0 are not disturbed )
  945.  
  946.  
  947. What the stack frame looks like:
  948.  
  949.  
  950. LONG    foo
  951. WORD    bar Total
  952. LONG    Cnt
  953.  
  954.  
  955. becomes...
  956.  
  957. foo    equ  -4
  958. bar    equ  -6
  959. Total  equ  -8
  960. Cnt    equ  -12
  961.  
  962.  
  963.         h  l           A5   base register
  964.         i  o           |
  965.         OOOO OO OO OOOOO    memory bytes
  966.   (-)   1119 87 65 4321
  967.         210
  968.  
  969.  
  970.  
  971. ( Sometimes variables are "adjusted" for proper loading, and
  972. "-2(a5)" or other displacement may appear in the output file
  973.  instead of "foo(a5)" or other variable you might be expecting. )
  974.  
  975.  
  976. *********************************************
  977.  
  978. How to get what you need, hints, etc.:
  979.  
  980.  
  981. END
  982.  
  983.     Data statements ( "dc.b", "ds.l" etc. ) should be
  984.     placed BELOW the "END" statement.  Any string
  985.     constants which are generated will also appear
  986.     below the "END".  Other "data" statements
  987.     ( "equ", "xref", "xdef" etc. ) can be placed ABOVE
  988.     your variables, or BELOW "END".
  989.     ( In the output .asm file "END" will be adjusted )
  990.  
  991. o    Instruction size:  In most cases you WON'T NEED
  992.     A SIZE ARGUMENT.  It knows the size of your variables,
  993.     address and data registers, and is smart enough to know
  994.     what size to use.  It determines the size of data by it's
  995.     actual value not its physical size.
  996.     ( $0020  %11010000  $12  125  are all BYTE size )
  997.     If the data is smaller than the instruction size you want,
  998.     ( d1 = $20 w ) or it can't know an operands size
  999.     ( (a2)+ = 3(a0) l ) you'll need to give it a size argument.
  1000.  
  1001.     Caution:  Be aware that if you load small variables into
  1002.           larger ones, the upper bytes arn't cleared and
  1003.           may garbage your result.  Always initialize your
  1004.           variables or restrict the size of the operation to
  1005.           "b" or "w".
  1006.  
  1007. o    Try not to overuse the size arguments.  Once you get confident
  1008.     it's sizing your instructions correctly ( by checking the
  1009.     .asm file ) you'll find you can eliminate their use almost
  1010.     entirely!  By needlessly restricting a long operation to
  1011.     a word, or byte, you can miss the "quick" optimization.
  1012.  
  1013. o    Since "(a1)" refers to the CONTENTS of the byte, word, or long
  1014.     that A1 points to, "($dff180)" is used in a similar way.
  1015.     "d0 = ($dff01e) w" is converted to "move.w  $dff01e,d0"
  1016.     ( decimal addr's are also valid: "(14675968)" )
  1017.  
  1018. o    When numbers are used as operands "$fe02" or "37", they are
  1019.     converted to "#$fe02" and "#37".  Operands that it
  1020.     doesn't recognize ( doesn't match with any declared 
  1021.     LONG, WORD, BYTE, or standard "(a1)+" etc. ) get output
  1022.     as is.  This is very useful when you need operands
  1023.     like: "#NewWin", "wd_UserPort(a1)", "$20(a1)", "DMACON(a6)"
  1024.  
  1025. o    Most instructions set condition code flags on the result of the
  1026.     operation.  Often, instead of using a compare to check the
  1027.     result, you can use a branch on condition instruction ( "beq",
  1028.     "bne" etc. ) to jump to a location on the state of a condition
  1029.     code flag.  You need to check which flags are set ( if any )
  1030.     for an instruction.
  1031.  
  1032. o    If at any time you're unsure of what a statement is being
  1033.     output as, or want to check something out, just look
  1034.     at the output file.  Well placed blank lines in your source
  1035.     code can enhance its readability.
  1036.  
  1037. o    I think it's a good idea to get away from using include files.
  1038.     Most assembly source files I see do this.
  1039.     It speeds up the assembler tremendously, and saves
  1040.     endless wear and tear on your drives.
  1041.  
  1042.  
  1043. *********************************************
  1044.  
  1045.  
  1046. Converting C to EZAsm:
  1047.  
  1048.  
  1049.     Its fairly easy to convert any C code into
  1050.     EZAsm if you follow these guidelines:
  1051.  
  1052.  
  1053.   Allocating structures:
  1054.  
  1055.     Whenever you see "struct VSprite SpriteA" etc.,    
  1056.     you need to either allocate some memory for the
  1057.     structure, or set up your own:
  1058.  
  1059.  
  1060. CLR_PUB    equ    $10001
  1061.  
  1062. LONG    SpriteA
  1063.  
  1064.  
  1065.     SpriteA = AllocMem( [structure size] #CLR_PUB )
  1066.     beq    Exit
  1067.  
  1068. ---------- or ----------------
  1069.  
  1070. SpriteA    ds.w    0    ;align
  1071.     dc.l    0    ;NextVSprite    
  1072.     dc.l    0    ;PrevVSprite
  1073.     .
  1074.     .
  1075.  
  1076.  
  1077.     ( you could use "#vs_SIZEOF" etc. for [structure size]    
  1078.     and let the assembler get its size from the includes )
  1079.  
  1080.     Some functions will create the structures for you
  1081.     and return a pointer to it ( OpenWindow( ), OpenScreen( )
  1082.     etc. ) just declare a LONG, and load the returned pointer:
  1083.  
  1084. LONG    Window
  1085.  
  1086.     Window = OpenWindow( #NewWindow )
  1087.     beq    Exit
  1088.  
  1089.  
  1090.   Referencing structures:
  1091.  
  1092.     Often you'll need to get at data inside structures.
  1093.     First load the "structure pointer" into an address
  1094.     register, then use the offset of the structure element.
  1095.     Here's a typical example:
  1096.  
  1097.     Move( Window->RPort, 20, 20 );    /* C */
  1098.  
  1099.  
  1100.     a0 = Window
  1101.     Move( wd_RPort(a0) 20 20 )
  1102.  
  1103.     ---- or ----
  1104.  
  1105.     a0 = Window    
  1106.     Move( 50(a0) 20 20 )
  1107.  
  1108.  
  1109.     ( add an include to your source, and the assembler
  1110.     will look up "wd_RPort" and substitute its offset or,
  1111.     if you have access to the offsets, use "50(a0)"
  1112.     instead of "wd_RPort(a0)" )
  1113.  
  1114.     ( it's Ok to use the same address register )
  1115.  
  1116.     a0 = Window
  1117.     a0 = wd_RPort(a0)
  1118.  
  1119.  
  1120.   Loops:
  1121.  
  1122.     I've often thought about trying to add at least a
  1123.     while( ) like statement, but it's just as easy
  1124.     to "code-your-own":
  1125.  
  1126.  
  1127.     for ( foo = 0; foo < 10; foo++ ) {    /* C */
  1128.  
  1129.     }
  1130.  
  1131.  
  1132.  
  1133. LONG    foo
  1134.  
  1135.  
  1136.     foo = 0        ;initialization statements..
  1137.  
  1138. Again:    .        ;body..
  1139.     .
  1140.  
  1141.     foo < 10 {    ;test, and other statements..
  1142.         foo ++
  1143.         jmp Again
  1144.     }
  1145.  
  1146.  
  1147.  
  1148.   Info:
  1149.  
  1150.     If you try converting statements one-for-one
  1151.     in C code that has lots of loops and complex
  1152.     statements, you can end up pulling your hair out,
  1153.     and end up with tons of code.  In cases like
  1154.     this, take a step back, and try to figure
  1155.     out the "idea" of what's going on, or what
  1156.     the final result will be, THEN try to think
  1157.     how you'd code it using EZAsm.
  1158.  
  1159.  
  1160.  
  1161. *********************************************
  1162.  
  1163. Errors:
  1164.  
  1165.  
  1166. "Illegal argument"
  1167.  
  1168.     The argument found was not valid for the operator.  See
  1169.     the list of "Optional Args" for the operator.  It must
  1170.     be lower case, and be separated from the operands
  1171.     by at least a space or a tab.
  1172.     
  1173. "Illegal operand"
  1174.  
  1175.     One, or both, of the operands are:  not valid for the operator,
  1176.     have an invalid number, or byte size was specified for an
  1177.     "An" operand ( {B} ).  In most cases it's looking for "Dn" or "An"
  1178.     as one of the operands.  ( look under the "legal operands"
  1179.     of the operator for a valid combination )
  1180.  
  1181. "Illegal size"
  1182.  
  1183.     The argument size you specified is not valid for the operator.    
  1184.     Check the "legal sizes" for the operator.
  1185.     
  1186. "Needs size argument"    
  1187.  
  1188.     It doesn't have enough size information about the operands to
  1189.     calculate an instruction size.
  1190.     You need to add an l, w, or b argument.
  1191.  
  1192. "Label not found"
  1193.  
  1194.     No label matching your label argument was found.    
  1195.  
  1196. "Brace mismatch"
  1197.  
  1198.     Checks are made when a closing brace ( "}" ) is hit, and when "END"
  1199.     is hit.  If the brace stack is "messed up" at that time, an error 
  1200.     is given.  If "}" is shown, look from there up.  Both "}" and "END"
  1201.     may appear.  If just "END", look for a "{" or "} else {" without a
  1202.     matching "}".
  1203.  
  1204. "Function not found"
  1205.  
  1206.     No function matching your function name was found.  Check case and    
  1207.     spelling of function name, and be sure there isn't a space before
  1208.     the "(".  Check the list of supported function names in the
  1209.     file "funcnm2".
  1210.  
  1211. "Function argument count incorrect"
  1212.  
  1213.     Check the number of arguments you used for the function.  Too many
  1214.     or not enough were used.  With string arguments, check for
  1215.     a missing '"'.  Also look for a missing end ")".
  1216.  
  1217.  
  1218. ( EZAsm doesn't do much checking of normal assembly statements.
  1219. A68k and Blink will catch any problems missed by EZAsm and bring
  1220. them to your attention )
  1221.  
  1222.  
  1223. *******************************************************************
  1224. *******************************************************************
  1225.  
  1226.  
  1227.     Try using it, I think you'll like it! 8^)
  1228.     I'm always trying to improve EZAsm, and I'd really like
  1229.     to hear any ideas you have on making it better,
  1230.     even your complaints.  So if you've found an
  1231.     "undocumented feature", or there's something you'd like
  1232.     to see in a future version, I'd be happy to hear from you.
  1233.  
  1234.     Enjoy!
  1235.  
  1236.  
  1237. You can reach me at:
  1238.  
  1239. Joe Siebenmann
  1240. 8303 Old Tree Court
  1241. Springfield, VA  22153
  1242. ( USA )
  1243.  
  1244. (703) 455-4982
  1245.  
  1246.  
  1247.